Add PHPStan extension banning panicking monad unwraps#19
Merged
Conversation
Ships a RestrictedMethodUsageExtension that flags the panicking escape-hatch methods on Result and Option: - Result::unwrap()/unwrapErr() and Option::unwrap() (may panic) - Err::unwrap(), Ok::unwrapErr(), None::unwrap() (always panic when the type is narrowed to the failing variant) Messages steer callers toward match(), expect()/expectErr(), unwrapOr()/unwrapOrElse() and mapOrElse(). Registered via extension.neon and composer's extra.phpstan.includes so consumers using phpstan/extension-installer pick it up automatically; the library's own analysis is unaffected. Includes a RuleTestCase covering every banned call and asserting safe calls are not flagged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
After isOk()/isErr() (Result) or isSome() (Option), the value is narrowed to the safe variant, so unwrap()/unwrapErr() must not be flagged. The exhaustive RuleTestCase assertion enforces no errors are emitted for these guarded calls. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
robertvansteen
approved these changes
Jun 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Ships a PHPStan extension (a
RestrictedMethodUsageExtension) that flags the panicking "escape-hatch" unwrap methods onResultandOption, nudging callers toward explicit handling.It reports two situations:
Result::unwrap()(throws onErr),Result::unwrapErr()(throws onOk)Option::unwrap()(throws onNone)Err::unwrap(),Ok::unwrapErr(),None::unwrap()Messages steer toward
match(),expect()/expectErr(),unwrapOr()/unwrapOrElse(), andmapOrElse()(the Option message deliberately omitsmatch(), whichOptiondoesn't have).How it's wired
extension.neonregisters the service under thephpstan.restrictedMethodUsageExtensiontag.composer.jsongainsextra.phpstan.includes, so consumers usingphpstan/extension-installerpick it up automatically.src/PHPStan/(namespaceSuperscript\Monads\PHPStan) so it's production-autoloaded for consumers.The library's own analysis is unaffected: it doesn't depend on
extension-installer, so its internalunwrap()usage (e.g.Option::collect()) isn't flagged.Tests
tests/PHPStan/NoPanickingMonadUnwrapExtensionTest.phpuses PHPStan'sRuleTestCasewith the built-inRestrictedMethodUsageRuleagainst a fixture. The exhaustive assertion verifies all six banned calls are flagged with their exact messages, and that safe calls (Ok::unwrap,Some::unwrap,match,unwrapOr) are not flagged.Verification
vendor/bin/pest tests/PHPStan— passesvendor/bin/phpstan analyse— library self-analysis stays cleancomposer validate— valid🤖 Generated with Claude Code